TypeScript Konfigurācija: Visaptveroša tsconfig.json Rokasgrāmata

TypeScript, JavaScript virskopa, ienes statisko tipizēšanu dinamiskajā tīmekļa izstrādes pasaulē. Pareizi konfigurēts tsconfig.json fails ir būtisks, lai pilnībā izmantotu TypeScript jaudu. Šī rokasgrāmata sniedz visaptverošu pārskatu par tsconfig.json, aptverot svarīgākās kompilatora opcijas, projekta iestatīšanu un uzlabotas konfigurācijas.

Kas ir tsconfig.json?

tsconfig.json fails ir konfigurācijas fails, kas norāda kompilatora opcijas TypeScript projektam. Tas norāda TypeScript kompilatoram, kā pārvērst (transpilēt) TypeScript kodu par JavaScript kodu. Šis fails ir būtisks, lai definētu projekta struktūru, iestatītu kompilācijas noteikumus un nodrošinātu konsekvenci izstrādes komandā neatkarīgi no tā, vai šī komanda atrodas vienā birojā vai ir izkliedēta vairākos kontinentos.

tsconfig.json faila izveide

Lai izveidotu tsconfig.json failu, terminālī dodieties uz sava projekta saknes direktoriju un izpildiet šādu komandu:

            tsc --init
            

              
                Copy
              
            
          

Šī komanda ģenerē pamata tsconfig.json failu ar biežāk lietotajām kompilatora opcijām. Pēc tam jūs varat pielāgot failu atbilstoši sava projekta specifiskajām prasībām. Tipisks tsconfig.json ietvers tādas opcijas kā compilerOptions, include un exclude.

Būtiskākās kompilatora opcijas

Sadaļa compilerOptions ir tsconfig.json faila sirds. Tā satur plašu opciju klāstu, kas kontrolē TypeScript kompilatora darbību. Šeit ir dažas no svarīgākajām kompilatora opcijām:

target

Opcija target norāda ECMAScript mērķa versiju ģenerētajam JavaScript kodam. Biežākās vērtības ietver ES5, ES6 (ES2015), ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext. Pareizā mērķa izvēle ir būtiska, lai nodrošinātu saderību ar paredzēto izpildes vidi, piemēram, pārlūkprogrammām vai Node.js versijām.

Piemērs:

            {
  "compilerOptions": {
    "target": "ES2020"
  }
}
            

              
                Copy
              
            
          

module

Opcija module norāda moduļu koda ģenerēšanas stilu. Biežākās vērtības ietver CommonJS, AMD, System, UMD, ES6 (ES2015), ES2020 un ESNext. Moduļu sistēmas izvēle ir atkarīga no mērķa vides un izmantotā moduļu saiņotāja (piemēram, Webpack, Rollup, Parcel). Node.js videi bieži tiek izmantots CommonJS, savukārt modernām tīmekļa lietojumprogrammām priekšroka tiek dota ES6 vai ESNext ar moduļu saiņotāju. Izmantojot ESNext, izstrādātāji var izmantot jaunākās funkcijas un optimizācijas, paļaujoties uz saiņotāju, kas nodrošinās gala moduļa formātu.

Piemērs:

            {
  "compilerOptions": {
    "module": "ESNext"
  }
}
            

              
                Copy
              
            
          

lib

Opcija lib norāda bibliotēkas failu sarakstu, kas jāiekļauj kompilācijā. Šie bibliotēkas faili nodrošina tipu definīcijas iebūvētajām JavaScript API un pārlūkprogrammas API. Biežākās vērtības ietver ES5, ES6, ES2015, ES2016, ES2017, ES2018, ES2019, ES2020, ES2021, ES2022, ESNext, DOM, WebWorker, ScriptHost, ES2015.Core, ES2015.Collection, ES2015.Iterable, ES2015.Promise, ES2015.Proxy, ES2015.Reflect, ES2015.Generator, ES2015.Symbol, ES2015.Symbol.WellKnown, ES2016.Array.Include, ES2017.object, ES2017.Intl, ES2017.SharedMemory, ES2017.String, ES2017.TypedArrays, ES2018.Intl, ES2018.Promise, ES2018.RegExp, ES2019.Array, ES2019.Object, ES2019.String, ES2019.Symbol, ES2020.BigInt, ES2020.Promise, ES2020.String, ES2020.Symbol.WellKnown, ES2021.Promise, ES2021.String, ES2021.WeakRef, ES2022.Error, ES2022.Object, ES2022.String, un daudzas citas. Atbilstošu bibliotēku izvēle nodrošina, ka TypeScript kompilatoram ir nepieciešamā tipu informācija mērķa videi. DOM bibliotēkas izmantošana ļauj projektam kompilēt kodu, kas izmanto pārlūkprogrammai specifiskas API, bez tipu kļūdām.

Piemērs:

            {
  "compilerOptions": {
    "lib": ["ES2020", "DOM"]
  }
}
            

              
                Copy
              
            
          

allowJs

Opcija allowJs ļauj TypeScript kompilatoram kompilēt JavaScript failus kopā ar TypeScript failiem. Tas ir noderīgi, lai pakāpeniski migrētu esošus JavaScript projektus uz TypeScript. Iestatot šo opciju uz true, kompilators var apstrādāt .js failus, ļaujot pakāpeniski ieviest TypeScript projektā.

Piemērs:

            {
  "compilerOptions": {
    "allowJs": true
  }
}
            

              
                Copy
              
            
          

jsx

Opcija jsx norāda, kā jāapstrādā JSX sintakse. Biežākās vērtības ietver preserve, react, react-native un react-jsx. preserve saglabā JSX sintaksi izvadē, savukārt react pārveido JSX par React.createElement izsaukumiem. react-jsx izmanto jauno JSX transformāciju, kas ieviesta React 17 un neprasa React importēšanu. Pareizas JSX opcijas izvēle ir būtiska projektiem, kas izmanto React vai citas uz JSX balstītas bibliotēkas.

Piemērs:

            {
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}
            

              
                Copy
              
            
          

declaration

Opcija declaration ģenerē atbilstošus .d.ts deklarāciju failus katram TypeScript failam. Deklarāciju faili satur tipu informāciju, un tos izmanto citi TypeScript projekti, lai patērētu kompilēto kodu. Deklarāciju failu ģenerēšana ir būtiska, lai izveidotu atkārtoti lietojamas bibliotēkas un moduļus. Šie faili ļauj citiem TypeScript projektiem saprast bibliotēkas piedāvātos tipus un saskarnes, nekompilējot sākotnējo pirmkodu.

Piemērs:

            {
  "compilerOptions": {
    "declaration": true
  }
}
            

              
                Copy
              
            
          

sourceMap

Opcija sourceMap ģenerē avota karšu (source map) failus, kas sasaista ģenerēto JavaScript kodu ar sākotnējo TypeScript kodu. Avota kartes ir būtiskas TypeScript koda atkļūdošanai pārlūkprogrammās un citās vidēs. Kad JavaScript kodā rodas kļūda, avota karte ļauj izstrādātājam redzēt atbilstošo TypeScript kodu atkļūdotājā, padarot problēmas identificēšanu un novēršanu vieglāku.

Piemērs:

            {
  "compilerOptions": {
    "sourceMap": true
  }
}
            

              
                Copy
              
            
          

outDir

Opcija outDir norāda izvades direktoriju ģenerētajiem JavaScript failiem. Šī opcija palīdz organizēt projekta būvējuma izvadi, atdalot pirmkodu no kompilētā koda. outDir izmantošana atvieglo būvēšanas procesa pārvaldību un lietojumprogrammas izvietošanu.

Piemērs:

            {
  "compilerOptions": {
    "outDir": "dist"
  }
}
            

              
                Copy
              
            
          

rootDir

Opcija rootDir norāda TypeScript projekta saknes direktoriju. Kompilators izmanto šo direktoriju kā bāzi moduļu nosaukumu atrisināšanai. Šī opcija ir īpaši svarīga projektiem ar sarežģītu direktoriju struktūru. Pareiza rootDir iestatīšana nodrošina, ka kompilators var atrast visus nepieciešamos moduļus un atkarības.

Piemērs:

            {
  "compilerOptions": {
    "rootDir": "src"
  }
}
            

              
                Copy
              
            
          

strict

Opcija strict ieslēdz visas stingrās tipu pārbaudes opcijas. Tas ir ļoti ieteicams jauniem TypeScript projektiem, jo tas palīdz atklāt potenciālās kļūdas agrīnā izstrādes posmā. Strikta režīma ieslēgšana piemēro stingrākus tipu pārbaudes noteikumus, kas noved pie robustāka un uzturēšanai vieglāka koda. Vislabākā prakse ir ieslēgt strikto režīmu visos jaunos TypeScript projektos.

Piemērs:

            {
  "compilerOptions": {
    "strict": true
  }
}
            

              
                Copy
              
            
          

esModuleInterop

Opcija esModuleInterop nodrošina savietojamību starp CommonJS un ES moduļiem. Tas ir svarīgi projektiem, kas izmanto abu veidu moduļus. Kad esModuleInterop ir ieslēgts, TypeScript automātiski apstrādā atšķirības starp CommonJS un ES moduļiem, atvieglojot moduļu importēšanu un eksportēšanu starp abām sistēmām. Šī opcija ir īpaši noderīga, strādājot ar trešo pušu bibliotēkām, kas var izmantot atšķirīgas moduļu sistēmas.

Piemērs:

            {
  "compilerOptions": {
    "esModuleInterop": true
  }
}
            

              
                Copy
              
            
          

moduleResolution

Opcija moduleResolution norāda, kā TypeScript atrisina moduļu importus. Biežākās vērtības ietver Node un Classic. Moduļu atrisināšanas stratēģija Node ir noklusējuma un balstās uz Node.js moduļu atrisināšanas algoritmu. Moduļu atrisināšanas stratēģija Classic ir vecāka un tiek lietota retāk. Node moduļu atrisināšanas stratēģijas izmantošana nodrošina, ka TypeScript var pareizi atrisināt moduļu importus Node.js vidē.

Piemērs:

            {
  "compilerOptions": {
    "moduleResolution": "Node"
  }
}
            

              
                Copy
              
            
          

baseUrl un paths

Opcijas baseUrl un paths tiek izmantotas, lai konfigurētu moduļu atrisināšanu nerelatīviem moduļu importiem. Opcija baseUrl norāda bāzes direktoriju nerelatīvu moduļu nosaukumu atrisināšanai. Opcija paths ļauj jums kartēt moduļu nosaukumus uz konkrētām vietām failu sistēmā. Šīs opcijas ir īpaši noderīgas projektiem ar sarežģītu direktoriju struktūru un moduļu importu vienkāršošanai. baseUrl un paths izmantošana var padarīt kodu lasāmāku un vieglāk uzturējamu.

Piemērs:

            {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}
            

              
                Copy
              
            
          

Iekļaušanas un izslēgšanas opcijas (Include and Exclude)

Opcijas include un exclude norāda, kuri faili jāiekļauj kompilācijā un kuri faili jāizslēdz. Šīs opcijas izmanto globālus modeļus (glob patterns), lai saskaņotu failu nosaukumus. include un exclude izmantošana ļauj jums kontrolēt, kurus failus apstrādā TypeScript kompilators, uzlabojot būvēšanas veiktspēju un samazinot kļūdas. Vislabākā prakse ir skaidri norādīt failus, kas jāiekļauj kompilācijā.

Piemērs:

            {
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
            

              
                Copy
              
            
          

Paplašināšanas opcija (Extends)

Opcija extends ļauj mantot kompilatora opcijas no cita tsconfig.json faila. Tas ir noderīgi, lai koplietotu kopīgus konfigurācijas iestatījumus starp vairākiem projektiem vai lai izveidotu bāzes konfigurācijas. Opcijas extends izmantošana veicina koda atkārtotu izmantošanu un samazina dublēšanos. Vislabākā prakse ir izveidot bāzes konfigurācijas un paplašināt tās atsevišķos projektos.

Piemērs:

            {
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "jsx": "react-jsx"
  },
  "include": ["src/**/*"]
}
            

              
                Copy
              
            
          

Uzlabotas konfigurācijas

Papildus būtiskajām kompilatora opcijām, tsconfig.json atbalsta uzlabotas konfigurācijas specializētiem scenārijiem.

Inkrementālā kompilācija

Lielos projektos inkrementālā kompilācija var ievērojami uzlabot būvēšanas laiku. TypeScript var kešot iepriekšējo kompilāciju rezultātus un pārkompilēt tikai tos failus, kas ir mainīti. Inkrementālās kompilācijas ieslēgšana var dramatiski samazināt būvēšanas laiku lieliem projektiem. Tas ir īpaši svarīgi projektiem ar lielu skaitu failu un atkarību.

            {
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}
            

              
                Copy
              
            
          

Projektu atsauces (Project References)

Projektu atsauces ļauj strukturēt lielus TypeScript projektus mazākos, neatkarīgos moduļos. Tas var uzlabot būvēšanas laiku un koda organizāciju. Projektu atsauču izmantošana var padarīt lielus projektus pārvaldāmākus un vieglāk uzturējamus. Vislabākā prakse ir izmantot projektu atsauces lieliem, sarežģītiem projektiem.

            {
  "compilerOptions": {
    "composite": true
  },
  "references": [
    { "path": "./module1" },
    { "path": "./module2" }
  ]
}
            

              
                Copy
              
            
          

Pielāgotas tipu definīcijas

Dažreiz jums var būt nepieciešams nodrošināt tipu definīcijas JavaScript bibliotēkām, kurām to nav. Jūs varat izveidot pielāgotus .d.ts failus, lai definētu šo bibliotēku tipus. Pielāgotu tipu definīciju izveide ļauj jums izmantot JavaScript bibliotēkas savā TypeScript kodā, nezaudējot tipu drošību. Tas ir īpaši noderīgi, strādājot ar mantotu JavaScript kodu vai bibliotēkām, kuras nenodrošina savas tipu definīcijas.

            // custom.d.ts
declare module 'my-library' {
  export function doSomething(x: number): string;
}
            

              
                Copy
              
            
          

Labākās prakses

• Izmantojiet strikto režīmu (Strict Mode): Iespējojiet opciju strict, lai uzlabotu tipu pārbaudi.
• Norādiet mērķi (Target): Izvēlieties atbilstošo target versiju savai izpildes videi.
• Organizējiet izvadi: Izmantojiet outDir, lai atdalītu pirmkodu no kompilētā koda.
• Pārvaldiet atkarības: Izmantojiet include un exclude, lai kontrolētu, kuri faili tiek kompilēti.
• Izmantojiet paplašināšanu (Extends): Koplietojiet kopīgus konfigurācijas iestatījumus ar opciju extends.
• Iekļaujiet konfigurāciju versiju kontrolē: Iesniedziet tsconfig.json Git repozitorijā, lai uzturētu konsekvenci starp izstrādātāju vidēm un CI/CD konveijeriem.

Biežāko problēmu novēršana

tsconfig.json konfigurēšana dažreiz var būt sarežģīta. Šeit ir dažas biežāk sastopamās problēmas un to risinājumi:

Moduļu atrisināšanas problēmas

Ja rodas moduļu atrisināšanas kļūdas, pārliecinieties, ka opcija moduleResolution ir pareizi konfigurēta un ka opcijas baseUrl un paths ir pareizi iestatītas. Pārbaudiet divreiz ceļus, kas norādīti opcijā paths, lai pārliecinātos, ka tie ir pareizi. Pārbaudiet, vai visi nepieciešamie moduļi ir instalēti node_modules direktorijā.

Tipu kļūdas

Tipu kļūdas var rasties, ja tipu definīcijas ir nepareizas vai trūkst. Pārliecinieties, ka jums ir instalētas pareizās tipu definīcijas visām bibliotēkām, kuras izmantojat. Ja izmantojat JavaScript bibliotēku, kurai nav tipu definīciju, apsveriet iespēju izveidot pielāgotas tipu definīcijas.

Kompilācijas kļūdas

Kompilācijas kļūdas var rasties, ja jūsu TypeScript kodā ir sintakses kļūdas vai tipu kļūdas. Rūpīgi pārskatiet kļūdu ziņojumus un izlabojiet visas sintakses vai tipu kļūdas. Pārliecinieties, ka jūsu kods atbilst TypeScript kodēšanas konvencijām.

Noslēgums

Labi konfigurēts tsconfig.json fails ir būtisks veiksmīgam TypeScript projektam. Izprotot būtiskākās kompilatora opcijas un uzlabotas konfigurācijas, jūs varat optimizēt savu izstrādes darbplūsmu, uzlabot koda kvalitāti un nodrošināt saderību ar mērķa vidi. Laika ieguldīšana pareizā tsconfig.json konfigurēšanā ilgtermiņā atmaksāsies, samazinot kļūdas, uzlabojot uzturējamību un optimizējot būvēšanas procesu. Tas nodrošina efektīvāku un uzticamāku programmatūras izstrādi. Šeit sniegtā informācija ir izstrādāta tā, lai tā būtu universāli piemērojama, un tai vajadzētu nodrošināt stabilu pamatu jauna projekta uzsākšanai ar TypeScript.

Atcerieties konsultēties ar oficiālo TypeScript dokumentāciju, lai iegūtu visjaunāko informāciju un detalizētus paskaidrojumus par visām pieejamajām kompilatora opcijām. TypeScript dokumentācija ir vērtīgs resurss, lai izprastu TypeScript konfigurācijas sarežģītības.